Python Argparse Avancerat: Bemästra underkommandon och anpassade actionklasser

Pythons argparse-modul är ett kraftfullt verktyg för att skapa kommandoradsgränssnitt (CLIs). Även om grundläggande användning är relativt enkel, erbjuder argparse avancerade funktioner som möjliggör skapandet av sofistikerade och användarvänliga CLIs. Detta blogginlägg fördjupar sig i två sådana avancerade funktioner: underkommandon och anpassade actionklasser.

Varför avancerad Argparse?

För enkla skript med bara några få alternativ kan grundläggande argparse-funktionalitet räcka. Men när dina skript växer i komplexitet och funktionalitet blir ett mer strukturerat och organiserat CLI viktigt. Avancerade argparse-funktioner hjälper till att:

• Förbättra användarupplevelsen: Ge ett tydligt och intuitivt gränssnitt för användare.
• Förbättra kodens underhållbarhet: Organisera din kod i logiska moduler, vilket gör den lättare att förstå och underhålla.
• Öka funktionaliteten: Stödja komplexa arbetsflöden och flera operationer inom ett enda skript.
• Främja återanvändbarhet: Skapa återanvändbara komponenter som kan tillämpas på olika delar av din applikation.

Underkommandon: Organisera komplexa CLIs

Underkommandon är ett sätt att gruppera relaterade kommandon under ett enda huvudkommando. Detta är särskilt användbart för applikationer som utför en mängd distinkta uppgifter. Tänk till exempel på Git. Det använder underkommandon flitigt: git commit, git push, git pull, och så vidare. Varje underkommando har sin egen uppsättning argument och alternativ.

Implementera underkommandon med argparse

För att implementera underkommandon med argparse använder du metoden add_subparsers(). Här är ett grundläggande exempel:

            
import argparse

# Create the main parser
parser = argparse.ArgumentParser(description='A simple example with subcommands')

# Create the subparser
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# Create the 'add' subcommand
add_parser = subparsers.add_parser('add', help='Add two numbers')
add_parser.add_argument('x', type=int, help='First number')
add_parser.add_argument('y', type=int, help='Second number')

# Create the 'subtract' subcommand
subtract_parser = subparsers.add_parser('subtract', help='Subtract two numbers')
subtract_parser.add_argument('x', type=int, help='First number')
subtract_parser.add_argument('y', type=int, help='Second number')

# Parse the arguments
args = parser.parse_args()

# Perform the action based on the subcommand
if args.command == 'add':
    result = args.x + args.y
    print(f'The sum is: {result}')
elif args.command == 'subtract':
    result = args.x - args.y
    print(f'The difference is: {result}')
else:
    parser.print_help()

            

              
                Copy
              
            
          

I detta exempel:

• Vi skapar en huvudparser med argparse.ArgumentParser().
• Vi lägger till en subparser med parser.add_subparsers(dest='command', help='Available commands'). Argumentet dest specificerar attributet som kommer att lagra namnet på det valda underkommandot.
• Vi skapar två underkommandon, 'add' och 'subtract', med subparsers.add_parser().
• Varje underkommando har sin egen uppsättning argument (x och y).
• Vi parsar argumenten med parser.parse_args().
• Vi kontrollerar värdet på args.command för att avgöra vilket underkommando som valdes och utför sedan motsvarande åtgärd.

För att köra detta skript skulle du använda kommandon som:

python your_script.py add 5 3
python your_script.py subtract 10 2

Avancerade underkommandotekniker

1. Använda funktioner för att hantera underkommandon

En mer organiserad strategi är att definiera separata funktioner för att hantera varje underkommando. Detta förbättrar kodens läsbarhet och underhållbarhet.

            
import argparse

def add(args):
    result = args.x + args.y
    print(f'The sum is: {result}')

def subtract(args):
    result = args.x - args.y
    print(f'The difference is: {result}')

# Create the main parser
parser = argparse.ArgumentParser(description='A simple example with subcommands')

# Create the subparser
subparsers = parser.add_subparsers(dest='command', help='Available commands')

# Create the 'add' subcommand
add_parser = subparsers.add_parser('add', help='Add two numbers')
add_parser.add_argument('x', type=int, help='First number')
add_parser.add_argument('y', type=int, help='Second number')
add_parser.set_defaults(func=add)

# Create the 'subtract' subcommand
subtract_parser = subparsers.add_parser('subtract', help='Subtract two numbers')
subtract_parser.add_argument('x', type=int, help='First number')
subtract_parser.add_argument('y', type=int, help='Second number')
subtract_parser.set_defaults(func=subtract)

# Parse the arguments
args = parser.parse_args()

# Call the function associated with the subcommand
if hasattr(args, 'func'):
    args.func(args)
else:
    parser.print_help()

            

              
                Copy
              
            
          

Här använder vi set_defaults(func=...) för att associera en funktion med varje underkommando. Sedan, efter parsning, anropar vi den lämpliga funktionen om den existerar.

2. Nästlade underkommandon

Du kan nästla underkommandon för att skapa ännu mer komplexa och hierarkiska CLIs. Tänk till exempel på en CLI för att hantera molnresurser:

cloud compute instance create --name my-instance --region us-east-1
cloud storage bucket list --project my-project

I detta exempel är cloud huvudkommandot, compute och storage är underkommandon, och instance och bucket är under-underkommandon.

3. Verkligt exempel: Verktyg för internationalisering

Föreställ dig ett verktyg för att hantera översättningar i en flerspråkig applikation. Du kan använda underkommandon för att organisera de olika operationerna:

translation tool add-language --code fr_FR --name "French (France)"
translation tool extract-strings --source-dir src
translation tool translate --target-language es_ES --source-file strings.pot

Denna metod möjliggör en tydlig separation av ansvarsområden och gör verktyget lättare att använda och underhålla, särskilt när man hanterar många språk och översättningsarbetsflöden som är tillämpliga i olika länder.

Anpassade Actionklasser: Skräddarsy argumentparsning

argparse låter dig definiera anpassade actionklasser för att anpassa hur argument bearbetas. Detta är användbart för scenarier där standardbeteendet för argumentbearbetning inte räcker. En actionklass är en klass som ärver från argparse.Action och åsidosätter metoden __call__.

Skapa en anpassad actionklass

Här är ett exempel på en anpassad actionklass som konverterar ett argument till versaler:

            
import argparse

class ToUpper(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if isinstance(values, list):
            setattr(namespace, self.dest, [v.upper() for v in values])
        else:
            setattr(namespace, self.dest, values.upper())

# Create the parser
parser = argparse.ArgumentParser(description='Example with custom action')

# Add an argument with the custom action
parser.add_argument('--name', action=ToUpper, help='Name to convert to uppercase')
parser.add_argument('--cities', action=ToUpper, nargs='+', help='List of cities to convert to uppercase')

# Parse the arguments
args = parser.parse_args()

# Print the result
if args.name:
    print(f'Name: {args.name}')
if args.cities:
    print(f'Cities: {args.cities}')

            

              
                Copy
              
            
          

I detta exempel:

• Vi definierar en klass ToUpper som ärver från argparse.Action.
• Metoden __call__ anropas när argumentet påträffas. Den tar följande argument:
  • parser: ArgumentParser-objektet.
  • namespace: Namespace-objektet där de parsade argumenten lagras.
  • values: Värde(n) för argumentet.
  • option_string: Alternativsträngen som användes för att anropa denna åtgärd (t.ex. --name).
• Inuti metoden __call__ konverterar vi värdet till versaler med values.upper() och lagrar det i namespace med setattr(namespace, self.dest, values.upper()).
• Vi lägger till ett argument till parsern med parser.add_argument('--name', action=ToUpper, help='Name to convert to uppercase'). Vi specificerar action-argumentet som vår anpassade actionklass.

För att köra detta skript skulle du använda kommandon som:

python your_script.py --name john
python your_script.py --cities london paris tokyo

Användningsfall för anpassade actionklasser

1. Validera indata

Du kan använda anpassade actionklasser för att validera indata och utlösa ett fel om indatan är ogiltig. Du kan till exempel skapa en actionklass som kontrollerar om en fil existerar eller om ett nummer ligger inom ett specifikt intervall.

            
import argparse
import os

class FileMustExist(argparse.Action):
    def __call__(self, parser, namespace, values, option_string=None):
        if not os.path.exists(values):
            raise argparse.ArgumentTypeError(f'File not found: {values}')
        setattr(namespace, self.dest, values)

parser = argparse.ArgumentParser(description='Example validating file existence.')
parser.add_argument('--input-file', action=FileMustExist, help='Path to input file.')

args = parser.parse_args()

print(f'Input file: {args.input_file}')

            

              
                Copy
              
            
          

2. Konvertera enheter

Du kan använda anpassade actionklasser för att konvertera enheter. Du kan till exempel skapa en actionklass som konverterar temperaturer från Celsius till Fahrenheit.

3. Hantera komplexa datastrukturer

Om du behöver parsa argument till komplexa datastrukturer (t.ex. dictionarys, listor med objekt) kan du använda anpassade actionklasser för att hantera parslogiken.

4. Exempel: Hantera tidszoner

Tänk dig en applikation som behöver hantera datum och tider i olika tidszoner. En anpassad actionklass skulle kunna användas för att parsa en datumsträng och konvertera den till en specifik tidszon med hjälp av bibliotek som pytz.

            
import argparse
import datetime
import pytz

class TimeZoneConverter(argparse.Action):
    def __init__(self, option_strings, dest, timezone=None, **kwargs):
        super().__init__(option_strings, dest, **kwargs)
        self.timezone = timezone

    def __call__(self, parser, namespace, values, option_string=None):
        try:
            dt = datetime.datetime.fromisoformat(values)
            if self.timezone:
                tz = pytz.timezone(self.timezone)
                dt = tz.localize(dt)
            setattr(namespace, self.dest, dt)
        except ValueError:
            raise argparse.ArgumentTypeError(f"Invalid date/time format.  Use ISO format (YYYY-MM-DDTHH:MM:SS): {values}")
        except pytz.exceptions.UnknownTimeZoneError:
            raise argparse.ArgumentTypeError(f"Invalid Timezone: {self.timezone}")

parser = argparse.ArgumentParser(description='Example with timezone conversion.')
parser.add_argument('--event-time', action=TimeZoneConverter, timezone='America/Los_Angeles', help='Event time in ISO format (YYYY-MM-DDTHH:MM:SS). Converts to America/Los_Angeles timezone.')

args = parser.parse_args(['--event-time', '2024-10-27T10:00:00'])

print(f'Event Time (Los Angeles): {args.event_time}')

            

              
                Copy
              
            
          

Detta exempel visar hur anpassade åtgärder kan hantera tidszonkonverteringar med hjälp av biblioteket pytz, vilket demonstrerar en mer sofistikerad användning som är globalt relevant.

Bästa praxis för att använda avancerad Argparse

• Håll det enkelt: Krångla inte till din CLI i onödan. Använd underkommandon och anpassade åtgärder endast när det är nödvändigt.
• Ge tydliga hjälpmeddelanden: Skriv tydliga och koncisa hjälpmeddelanden för varje kommando och argument. Använd argumentet help i add_argument() flitigt.
• Validera indata: Validera alltid användarindata för att förhindra fel och säkerhetsbrister.
• Använd konsekventa namnkonventioner: Följ konsekventa namnkonventioner för kommandon, argument och alternativ. Överväg att använda kebab-case (--my-option) för långa optionsnamn.
• Testa noggrant: Testa din CLI noggrant med olika indata och scenarier.
• Dokumentera din CLI: Tillhandahåll omfattande dokumentation för din CLI, inklusive exempel på hur man använder varje kommando och argument. Verktyg som Sphinx kan generera dokumentation från din kod.
• Överväg lokalisering: Om din CLI är avsedd för en global publik, överväg att lokalisera dina hjälpmeddelanden och annan användarriktad text.

Slutsats

Underkommandon och anpassade actionklasser är kraftfulla verktyg för att skapa sofistikerade och användarvänliga CLIs med argparse. Genom att bemästra dessa avancerade funktioner kan du bygga robusta, underhållsbara och skalbara kommandoradsapplikationer som möter behoven hos en mångsidig användarbas. Från att hantera flerspråkiga applikationer till att hantera tidszoner över hela världen är möjligheterna stora. Använd dig av dessa tekniker för att lyfta din Python-skriptning och utveckling av kommandoradsverktyg till nästa nivå.